import { Meta } from '@storybook/addon-docs/blocks'

<Meta title="Using Contentful" />

# Using Contentful

The COVID Project website maintains content in Contentful. While Contentful [has exhaustive documentation](https://www.contentful.com/developers/docs/), this document covers how to manage content for the project website.

There is a single "space" in Contentful: **Website Content**. 

## Editing content within the website

Since some pages are a mix of Contentful snippets and other elements, finding what-goes-where is sometimes confusing. To find all editable parts of a page on the website, add `?edit` to the end of the URL and blue "Edit this content" buttons will appear over all editable areas of the page.

## Previewing changes

If you want to preview a piece of content, you can edit or create content in a separate "preview" section of Contentful. Any content published in this preview environment will not be published to the covidtracking.com website, but instead be published to [https://contentful-preview--upbeat-lovelace-3e9fff.netlify.app/](https://contentful-preview--upbeat-lovelace-3e9fff.netlify.app/).

- When you are in Contentful, you can click the menu in the upper-left, then the teensy arrow near "Website content" to view all environments in Contentful. Select "Preview" to switch to the preview environment.
- Anything you do in preview will NOT show up on the main website. However, they will trigger a test build of the website.
- The upper-left will show you which environment you are in. Only the green "master" environment is content that will make it to covidtracking.com when it is published.

## Managing content

You manage content in the **Content** tab on top of the screen. This will list all the content on the site. You can search and filter to find existing content. To add content, use the **Add a...** button on the upper-right.

Note that there is no **Save** button when editing content, it’s all saved automatically and only makes it to the website when you hit the Action Button in the upper-right when editing a page. This might read **Published**, **Changed**, or **Draft**, depending on what state the content is in. When you click on it, you will see several possible actions: Publish, Unpublish, or Archive. The first two are self-explanatory. **Set Schedule** lets you publish or unpublish content automatically at a set time.

Content is either **Published**, in **Draft**, or **Archived**. Only the published version of content makes it to the public website. Any piece of content can have a Published version, while there could be newer Drafts available for authors to edit and collaborate on. This content will show as **Changed**, and you can view all the history of the content on the right-side pane while editing.

When editing things like the body of a page or blog post, you are editing in **Markdown**. There are the standard editing tools available to you, but it will look a little like computer code. Use the Preview tab to make sure your edits will look as you expect.

To add images, click the **Insert Media** button. You can add existing media, or upload a new one. When adding media, there are options to crop and resize the image so it’s not huge.

## Slug?

You will see the term “slug” all over Contentful. We use it as a short-hand for a URL-compatible string. Some content uses the slug for the page URL (i.e. “about”), while others use it as a unique ID.

## How content makes it to the website

The website is automatically rebuilt twice an hour, and any changes in Contentful that are published will make it to the website during that time.

Whenever you Publish or Unpublish/archive a piece of content, the website is asked to rebuild automatically. It can take several minutes for this to happen.

## Managing the Blog

To edit blog posts, select the Content tab on top of the screen, you’ll see a list of all content on the website, and can filter by just Blog posts.

<div style={{padding: '1rem', background: '#efbbab'}}>
<strong>IMPORTANT:</strong> The website always expects there to be at least one blog post. If you unpublish all of them, the website won’t build.
</div>

Blog posts have the following fields:

- Title - The title
- Featured image - This image is displayed on top of the blog post, within the lede.
- Lede - A short sentence summarizing the blog post. Will be used in social cards, blog listings, and on top of the post.
- Author(s) - You can related one or more "Author" content types to a blog post. Authors should at least have a name and headshot.
- Body (for search) - Because our blog post content are complicated structures, pasting in the raw text of the blog post makes it easier for our search index.
- Blog content - A rich text field that allows embedding other content. Covered below.
- Slug - The URL of this blog post
- Publish date - The date to show on the blog post.
- Related blog posts - You can relate a post to others, and the related posts will show below this blog post.
- Categories - One or more blog categories.
- Social card - The [social card](#social-cards) associated with this blog post. If not used, the lede will be used instead.

### Body field Rich text

The body field has a familiar layout for setting text to bold, creating links, and adding headlines. You can also embed other pieces of content within the blog post. These include:

- Image - An image with an optional caption.
- Table - A table. To create your table, you will need to paste in the table in [Markdown format](https://www.tablesgenerator.com/markdown_tables).

## Managing pages

Regular web pages, like “About our Data” are called "Pages" in Contentful.

Pages have the following fields:

- Title - The page Title
- Body - The page body
- Slug - Slug
- Navigation Group - (optional) - Assign this page to a navigation group, see below

## Navigation groups

Use a Navigation Group to define the relationships between several pages in the header navigation. Navigation groups build this interface in the header:

Pages should be assigned to a group both in the Page editing screen (using the Navigation Group field), and in the Navigation Group itself.

When you edit a Navigation Group, you will see a list of all the pages in the group. You can drag them around to re-order them.

You can either add a Page in Contentful to a Navigation gorup, or a Navigation Link. Navigation Links are a simple navigation item that links to an external resource, or a page in the website that is not managed in Contetful (i.e. the “/data” page). To add a new Navigation link to a Navigation Group, just click the Create new Entry and Link button under its list of pages, and select Navigation Link. You will see a Title and a URL field. To add a link to a page on the project website, start the URL with a “/” character.

## Snippets

Snippets are pieces of content that live on a page not managed in Contentful. Several pages like the “Data” or “US Totals” pages are special pieces of content that are built using the project data, and are not managed in Contentful. However, we want things like preambles in those pages to be easily editable.

When you search for Snippets, you will see they have descriptive titles. Each snippet has the following fields:

- Name - A description of where the snippet goes
- Slug - Slug
- Description - A longer description for editors and authors about the snippet
- Content - The snippet content.

New snippets must be assigned by a developer to a place on the website. Unlike blog posts, pages, or navigation, any new snippets do not appear on the website automatically. Edits to snippets get pushed to the website like all the rest of the content.

## Social cards

Social cards define what people see when they paste in a URL to our website in social platforms. They have an associated image, title, and description.

For blog posts and pages, you can create a new social card to add a better sharing experience for that post. Theese are not required, and if not used, a generic card will be created for your page.

To create a new social card, select "Create new entry" under the "Social card" field of your post. You will need to upload an image of a specific dimension, or re-use one of our already uploaded card images.
